from __future__ import annotations
from typing import Any, Optional, Protocol, Sequence, Union


# ---------- 协议：可读/可写适配器 ----------


class Readable(Protocol):
    def read(
        self, batch_size: int = 1, timeout: Optional[float] = None
    ) -> Union[Any, Sequence[Any]]:
        """
        拉取数据。返回单个 item，或 item 序列。
        - batch_size: 建议外部队列一次最多返回多少条
        - timeout: 轮询阻塞超时（秒）；None 则由适配器自行决定
        """
        pass


class Writable(Protocol):
    def write(self, item: Any) -> None:
        """将 item 写入外部队列/存储"""
        pass
